feat: add Castle.customize/1 as the release integration API - #27

Refs #12. Targets release/1.0.0.

One public call makes a Mix release Castle-capable, so a consumer's mix.exs never names Forecastle:

my_app: fn ->
  [steps: [:assemble, :tar]] |> Castle.customize()
end

Deliberately thin

Forecastle.steps/1 already does the whole splice — finds :assemble, puts the pre-assembly step before it and the post-assembly step after, leaves everything around them where it was — and has shipped since 0.1.3. So this is Keyword.update(opts, :steps, Forecastle.steps(@default_steps), &spliced/1) and there is no second implementation of the splice. That the function is Forecastle's is the one thing customize/1 exists to keep out of a consumer's project.

The issue's "preserve existing custom steps and their ordering" therefore comes for free rather than being new code.

The :tar decision, and a claim it corrected

Absent :steps defaults to [:assemble, :tar], not Mix's [:assemble].

:steps supplied without :tar is honoured, with a build-time warning — not refused. The reasoning matters because the obvious argument for refusing is wrong: :release_handler's do_unpack_release/4 reads filename:join(RelDir, ReleaseName ++ ".tar.gz"), where ReleaseName is the version being installed. A running release needs no tarball of its own, so a base deployment shipped as a directory — a container image — built with steps: [:assemble] is a perfectly good Castle deployment. Refusing it would refuse a working configuration. The accurate claim is narrower: such a release can never be the target of an upgrade.

And the warning asserts no verdict. It can see one atom missing from the list as given; it cannot see whether an archive appears anyway, because a function step later in the list can pack one itself or add :tar to the steps still to run — %Mix.Release{} carries the remaining steps precisely so a step can. An earlier revision said the release "is never packed" and "nothing can install this version", then acknowledged the counterexample in a trailing sentence without retracting either: a definite diagnosis on the error channel, sending an operator after a packaging failure that may not exist. It now states the condition observed and what follows unless something else packs it.

Two cases the issue did not name

• No :assemble — passed through silently. Mix.Release.validate_steps!/1 requires exactly one, refuses the release and names the option, and Mix validates after the lazy release function runs, so its refusal is always downstream. A second implementation of Mix's rule could only drift from it.
• A :steps value that is not a list — handed back, because Forecastle.steps/1 guards on is_list/1 and a FunctionClauseError out of it would surface a module the project never mentioned, which is exactly what customize/1 exists to prevent. Pinned by a test so it is not a dead branch.

What it does not cover

Documented in the @doc rather than left to be discovered: the :appup project key with compilers: Mix.compilers() ++ [:appup], running mix forecastle.relup as a build step, include_executables_for: [:unix] (Windows is unsupported), and the optional rel/env.sh.eex. The lazy fn -> … end form is documented too, with the reason — it is what guarantees the dependency is compiled before the customisation runs.

Scope

@doc and @spec for customize/1 only. The module's @moduledoc is still the mix new placeholder and the rest of the API is undocumented: that is #11, and doing it here would mean editing #11's own limitation entry. Forecastle is untouched — in particular its fixture stays on explicit pre_assemble/post_assemble steps, because Forecastle has to remain testable without Castle's API.

Tests

142 → 154, twelve new cases. Every assertion is on the whole :steps list in order, with surrounding custom steps bound as values so identity comparison pins them — a case that only checked :steps was present would pass against a broken splice. The missing-:tar decision is pinned in both halves: the list is built as written and the warning fires, so a customize/1 that quietly appended :tar fails. async: false, because the warning is observed through Mix.Shell.Process and Mix's shell is one setting for the node.

Verification

mix precommit green — 154 tests, credo --strict clean — and compile --warnings-as-errors clean under Elixir 1.20.3/OTP 28, where the type inference is what caught a provably-dead branch earlier in this series.

mix docs also caught a factual error while this was being written: the @doc claimed :tar is Mix.Release.make_tar/1. It is not — make_tar/1 is defp in Mix.Tasks.Release and not callable. Corrected in the doc, the code comment and AGENTS.md; the argument survives in the weaker, true form, that a function step can pack a tarball itself.